<?php
/**
 *
 * This file contains {@link Domain51_Service_Delicious_Posts}
 *
 *
 * @package Domain51
 *
 * @subpackage Domain51_Service
 *
 * @author Travis Swicegood <development [at] domain51 [dot] com>
 *
 * @license http://opensource.org/licenses/bsd-license.php BSD
 *
 */


/**
 *
 * Required interface for connection
 *
 */
Solar::loadClass('Domain51_Util_Service_Connection');


/**
 *
 * The object that handles formatting requests for posts API calls to 
 * del.icio.us
 *
 * This class should not be instantiated directly when used during normal use,
 * instead it should be referenced via {@link Domain51_Service_Delicious}.
 *
 *
 * @package Domain51
 *
 * @subpackage Domain51_Service
 *
 * @author Travis Swicegood <development [at] domain51 [dot] com>
 *
 * @license http://opensource.org/licenses/bsd-license.php BSD
 *
 * @see Domain51_Service_Delicious
 *
 */ 
class Domain51_Service_Delicious_Posts
{
    private $_connection = null;
    
    
    /**
     *
     * Handle instantiation
     *
     *
     * @param Domain51_Util_Service_Connection $connection
     *
     * @see Domain51_Service_Delicious
     *
     */
    public function __construct(Domain51_Util_Service_Connection $connection) {
        $this->_connection = $connection;
        Solar::loadClass('Domain51_Service_Delicious_Posts_Container');
    }
    
    
    /**
     *
     * Returns posts matching the arguments by performing a 
     * <code>posts/get</code> API call.
     *
     * If no date or url is supplied, most recent date will be used.
     *
     * See del.icio.us {@link http://del.icio.us/help/api/posts API help page}
     * for full explaination from del.icio.us.
     *
     *
     * @param string $tag Tag to filter request by (optional)
     *
     * @param string $dt Full ISO datetime to filter request by (optional)
     *
     * @param string $url URL to filter request by (optional)
     *
     * @return Domain51_Service_Delicious_Posts_Container
     *
     */
    public function get($tag = '', $dt = '', $url = '') {
        $params = array();
        if (!empty($tag)) {
            $params[] = 'tag=' . urlencode($tag);
        }
        
        if (!empty($dt)) {
            $params[] = 'dt=' . urlencode($dt);
        }
        
        if (!empty($url)) {
            $params[] = 'url=' . urlencode($url);
        }
            
        $uri = 'posts/get?' . implode('&', $params);
        return new Domain51_Service_Delicious_Posts_Container($this->_connection->doRequest($uri));
    }
    
    
    /**
     *
     * Returns a list of the most recent posts to del.icio.us filtered by 
     * optional arguments, by performing a <code>posts/recent</code> API call.
     *
     * See del.icio.us {@link http://del.icio.us/help/api/posts API help page}
     * for full explaination from del.icio.us.
     *
     *
     * @param string $tag Tag to filter request by (optional)
     *
     * @param int $count Number of results to return (optional: max 100)
     *
     * @return Domain51_Service_Delicious_Posts_Container
     *
     */
    public function recent($tag = '', $count = 100) {
        $params = array();
        
        if (!empty($tag)) {
            $params[] = 'tag=' . urlencode($tag);
        }
        
        if (!empty($count)) {
            if ($count > 100) {
                $count = 100;
            }
            
            $params[] = 'count=' . (int)$count;
        }
        
        $uri = 'posts/recent?' . implode('&', $params);
        return new Domain51_Service_Delicious_Posts_Container($this->_connection->doRequest($uri));
    }
    
    
    /**
     *
     * Returns all posts by performing a <code>posts/all</code> API call.
     *
     * del.icio.us asks that this be used <i>sparingly</i>, if at all.  They ask
     * that {@link update()} be called prior to making this call to insure that
     * it is even necessary.
     *
     *
     * @param string $tag Tag to filter request by (optional)
     *
     * @return Domain51_Service_Delicious_Posts_Container
     *
     * @see update()
     *
     */
    public function all($tag = '') {
        $params = !empty($tag) ? 'tag=' . $tag : '';
        $uri = 'posts/all?' . $params;
        return new Domain51_Service_Delicious_Posts_Container($this->_connection->doRequest($uri));
    }
    
    
    /**
     *
     * Returns a list of dates and number of posts for each date by performing
     * a <code>posts/dates</code> API call.
     *
     *
     * @param string $tag Tag to filter request by (optional)
     *
     * @return Domain51_Service_Delicious_Posts_Container
     *
     */
    public function dates($tag = '') {
        $params = !empty($tag) ? 'tag=' . $tag : '';
        $uri = 'posts/dates?' . $params;
        return new Domain51_Service_Delicious_Posts_Container($this->_connection->doRequest($uri), 'date');
    }
    
    
    /**
     *
     * Adds a post to del.icio.us by performing a <code>posts/add</code> API
     * call.
     *
     *
     * @param string $url URL to be added
     *
     * @param string $description Description of the item
     *
     * @param string $extended Notes for the item
     *
     * @param string $tags Space separated tags for item (optional)
     *
     * @param string $dt Datetime for item in the ISO8601 format with literal T 
     *                   and Z (i.e., "CCYY-MMDDThh:mm:ssZ") (optional)
     *
     * @param string $replace Set to "no" if you wish to not replace/update 
     *                        an item with a matching URL.
     *
     * @param string $shared Set to "no" if you wish to not share this item.
     *
     * @return boolean Returns <code>true</code> on success, 
     *                 <code>false</code> on failure.
     *
     */
    public function add($url, $description, $extended = '', $tags = '', $dt ='', $replace = '', $shared = '') {
        $params = array();
        $params[] = 'url=' . urlencode($url);
        $params[] = 'description=' . urlencode($description);
        if (!empty($extended)) {
            $params[] = 'extended=' . urlencode($extended);
        }
        if (!empty($tags)) {
            $params[] = 'tags=' . urlencode($tags);
        }
        if (!empty($dt)) {
            $params[] = 'dt=' . urlencode($dt);
        }
        if (!empty($replace) && $replace == 'no') {
            $params[] = 'replace=no';
        }
        if (!empty($shared) && $shared == 'no') {
            $params[] = 'shared=no';
        }
        
        $uri = 'posts/add?' . implode('&', $params);
        $responseXml = $this->_connection->doRequest($uri);
        return ((string)$responseXml['code'] == 'done');
    }
    
    
    /**
     *
     * Delete a post from del.icio.us by performing a <code>posts/delete</code>
     * API call.
     *
     *
     * @param string $url The URL of the item to remove
     *
     * @return boolean Returns true on success.  As del.icio.us does not report
     *                 anything other than "done" as the response, there is no
     *                 way to determin if this did not succeed, so as of the
     *                 writing of this documentation, this will always return
     *                 <code>true</code>.
     *
     */
    public function delete($url) {
        $uri = 'posts/delete?url=' . urlencode($url);
        $responseXml = $this->_connection->doRequest($uri);
        return ((string)$responseXml['code'] == 'done');
    }
    
    
    /**
     *
     * Returns a string with the ISO datetime of the last update by performing
     * a <code>posts/update</code> API call.
     *
     *
     * @return string Datetime string in CCYY-MMDDThh:mm:ssZ format 
     *
     */
    public function update() {
        $uri = 'posts/update';
        $responseXml = $this->_connection->doRequest($uri);
        return (string)$responseXml['time'];
    }
}

?>